
//Copyright 1997-2009 Syrinx Development, Inc.
//This file is part of the Syrinx Web Application Framework (SWAF).
// == BEGIN LICENSE ==
//
// Licensed under the terms of any of the following licenses at your
// choice:
//
//  - GNU General Public License Version 3 or later (the "GPL")
//    http://www.gnu.org/licenses/gpl.html
//
//  - GNU Lesser General Public License Version 3 or later (the "LGPL")
//    http://www.gnu.org/licenses/lgpl.html
//
//  - Mozilla Public License Version 1.1 or later (the "MPL")
//    http://www.mozilla.org/MPL/MPL-1.1.html
//
// == END LICENSE ==
using System;
using System.Collections;

namespace Swaf.Gui
{
	/// <summary>
	/// Used when the <c>OnActionChange</c> event is fired to indicate which element
	/// of the action was changed.</summary>
	public enum ActionChangeType {Enabled, OperationState, ParameterOptions, Availability};

	/// <summary>Used by <c>IAction</c> for its <c>OnActionChange</c> event.</summary>
	public delegate void ActionChanged(object sender, ActionChangeType type);

	public enum ActionAvailability {notSet, none, disabled, enabled };

	/// <summary>
	/// Maintains state information about an action that can be taken against an object, 
	/// and supports triggering the action for execution.</summary>
	/// <remarks><c>IBusinessProcess</c> objects typically exposes a collection of objects
	/// that implement this interface to provide state information about actions that
	/// can be taken against them.</remarks>
	public interface IAction : IDescriptive
	{
		IBusinessProcess ParentProcess { get;}
		/// <summary>
		/// Event is fired when either <c>Enabled</c>, <c>OperationState</c>, or
		/// <c>ValidParameterOptions</c> is changed in the action object.</summary>
		event ActionChanged ActionChanged;

		/// <summary>The public id for the action.</summary>
		/// <remarks>This shouldn't represent something that is displayed directly to a user,
		/// but rather as a key when looking at a set of IAction objects.</remarks>
		string Id {get;}

		/// <summary>Indicates wether the IAction is enabled for operations.</summary>
		bool Enabled { get; }

		ActionAvailability Availability { get;}

		/// <summary>The list of possible operation states the given action can be in.</summary>
		/// <remarks>This should never return null, so if an action doesn't have operation
		/// states, this sould return a list with zero elements.</remarks>
		IList States{get;}

		/// <summary>The current operation state the action is in.</summary>
		/// <remarks>This can return null if the action doesn have operation states.</remarks>
		string CurrentOperationState {get;}

		/// <summary>If the action is triggered with a parameter, this will be true if the
		/// action supports any value being passed in as a parameter.</summary>
		/// <remarks>If no parameter is taken or if only parameters from the 
		/// <c>ValidParameterOptions</c> list can be used.  If an action takes
		/// no parameters this should return False and <c>ValidParameterOptions</c>
		/// should return a list with zero elements.</remarks>
		bool AllowsOpenParameters {get;}

		/// <summary>If the action is triggered with a parameter and has a limited collection of
		/// values that can be passed as a parameter, this is the list of valid values.</summary>
		/// <remarks>This should never return null, so if an action doesn't support
		/// takeing parameters or takes any value for a parameter, this should return a list
		/// with zero elements in it.</remarks>
		IList ValidParameterOptions {get;}

        /// <summary>
        /// When an action has a list of parameters, this defines which parameter is the
        /// currently being used.  This is useful when a user can trigger a specific parameter
        /// and that parameter because the current one.
        /// </summary>
        object CurrentParameterOption { get;}

		/// <overload>triggers the action to execute its behavior, which is unique to each
		/// implementation of this interface.</overload>
		/// <summary>Triggers the action with no parameters. If return false, indicates to cancel action
		/// and not to trigger any other actions associated with the event.</summary>
		bool trigger();

		/// <summary>triggers the action with a parameter. If return false, indicates to cancel action
		/// and not to trigger any other actions associated with the event.</summary>
		/// <param name="parameter">a value to pass for the action to use in its
		/// execution process.</param>
		bool trigger(object parameter);

	}
}
